NOTE: This file is formatted for printing. To print on LaserJet
compatible laser printers, simply type from DOS:
copy ripkit.doc prn
For other laser printers or for dot matrix printers, you may need
to paginate the document or otherwise reformat it or add printer
codes in order to print it directly.
eSoft's TBBS RIP Kit
Version 2.3
A Series of Sample Files and Instructions
for Adding Remote Imaging Protocol Support to TBBS 2.3
Copyright (C) 1995 Philip L. Becker, Ltd.
PLEASE NOTE: This product is copyrighted, including all programs,
sample files and documentation. However, you are permitted to
make and distribute copies of the product as desired, for any
reason, and include modifications if you wish, provided you do not
represent any copies you make as the original eSoft-provided TBBS
RIP Kit. This official TBBS RIP Kit is available only from eSoft,
Inc., and eSoft will provide technical support only for copies
obtained directly from eSoft.
RIP, RIPscrip, RIPaint, RIPterm and Remote Imaging Protocol are
trademarks of TeleGrafix Communications, Inc.
+----------------------------------------------------------+
| IMPORTANT WARNING! |
| |
| eSoft does provide technical support for the TBBS RIP |
| Kit, when the kit is purchased from eSoft. |
| |
| Please understand that we cannot provide you with |
| training or support regarding the RIPscrip protocol |
| itself, or with products that are not those of eSoft, |
| such as RIPaint, RIPterm, etc. You will need to obtain |
| assistance with the RIPscrip protocol itself from other |
| sources, and you will need to obtain technical support |
| with non-eSoft products from the makers of those |
| products. |
| |
| We also cannot assist you with changes you make or want |
| to make to the RIP.LNG language file. There are complex |
| and not always obvious interactions between various |
| elements of the language file; make changes to the |
| language file at your own risk. |
+----------------------------------------------------------+
INTRODUCTION
RIP, the Remote Imaging Protocol, has taken the BBS community by
storm since it was demonstrated at ONE BBSCON '92 in Denver.
Many BBS software vendors and terminal software vendors have
announced RIP support.
Our feeling is that RIP is not in its current form an ideal
solution for providing online graphical interfaces for a BBS, any
more than ANSI was an ideal solution for character based display
enhancement. RIP does provide a number of very interesting (and in
some cases quite elegant) features that help to "jazz up" a BBS
quickly and easily with graphical elements. In its current form,
however, RIP 1.x does not provide many of the features we've heard
our customers ask us for. For example, there is no direct
support for menu bars, pull-down menus, dialog boxes, scrolling
pointer select lists, input fields, pop-up menus, scalable
windows, etc. -- user interface elements that have been
popularized by the Microsoft Windows operating environment.
RIP is also not as easy to work with as many people might wish.
Although it's trivially simple to create screens for RIP,
implementing RIP in things like TBBS' language file, in TDBS
applications, or other places where a simple direct file display
is not possible or not desirable, it's not quite so easy to work
with.
Despite its drawbacks, RIP offers a number of terrific features.
It has support for a mouse, graphical icons, "hot" mouse regions,
definable variables, a variety of vector imaging techniques,
screen save and restore, and a number of others.
The demand for RIP has exploded, and TBBS sysops have been
anxious to have a packaged solution to offer a RIP interface to
their callers.
WHAT'S INVOLVED IN IMPLEMENTING RIP ON TBBS 2.3
RIP implementation involves two general areas:
1) The TBBS language file.
2) TBBS menu displays.
The purpose of TBBS 2.3 RIP support, therefore, is to:
1) Provide a TBBS language file with RIP codes in it.
2) Provide RIP sample menus which can be modified
without knowledge of the RIPscrip protocol.
3) Provide internal TBBS RIP support to make bulding
RIP menus easier.
4) Document and discuss your various options for RIP.
The language file is needed in order to make the internal
displays of TBBS graphical in nature for RIP users. The menu
displays of course are needed to make your menus graphical for
RIP users.
INSTALLING RIP SUPPORT IN TBBS 2.3
RIP support can be installed using the eSoft 2.3 INSTALL program
located on disk one of your TBBS software. Here is a list of your
options and what steps the INSTALL program will perform for each:
If you are installing TBBS for the first time, you can select
the RIPkit installation and install the RIP Sample Menus as
well. At that point, you are up-and-running with a
RIP-capable system in minutes. There are the steps that the
INSTALL program follows for you in this case:
1. Install the RIP.LNG 2.3 language file.
2. Create a LANGUAGE.BBS file.
3. Enable multi-language support in TBBS (by modifying
the RUNBBS.BAT file).
4. Create a RIP.CFG configuration file so that
RIP menu commands are executed properly, and
the initial RIP poll is enabled.
5. Ensure that CEDIT (CONFIG.CTL) has the necessary
language settings for RIP operation.
6. Install the RIP Sample Menus.
If you already have an existing TBBS system, but would like
to add RIP emulation to it with RIPkit 2.3, you can select
the Install RIPkit option from the INSTALL program menu. The
RIP.LNG language file will be installed, but the RIP sample
menus will not. Therefore, RIP callers will see a RIP
version of all menu commands, but they will still see your
existing non-RIP menus. Here are the steps that the INSTALL
program follows for you in this case:
1. Install the RIP.LNG 2.3 language file.
2. Create a LANGUAGE.BBS file.
3. Enable multi-language support in TBBS (by modifying
the RUNBBS.BAT file).
4. Create a RIP.CFG configuration file so that
RIP menu commands are executed properly, and
the initial RIP poll is enabled.
5. Ensure that CEDIT (CONFIG.CTL) has the necessary
language settings for RIP operation.
6. Create a top level menu which redirects the RIP
caller to your existing non-RIP top level menu
(MENU0000.CTL).
CONVERTING FROM TBBS 2.2 RIP KIT INSTALLATIONS
If you already have a TBBS system, and already have RIPkit
version 1.0 or 1.1 installed, then you can select the RIPkit
upgrade from the INSTALL program. The new 2.3 RIP language
file would replace your existing RIP.LNG file (ANY
CUSTOMIZATIONS YOU HAVE MADE ON YOUR OWN TO YOUR EXISTING
RIP.LNG FILE WILL BE LOST). No changes are made to your menu
structure whatsoever. These steps are followed by INSTALL
for you:
1. Replace the existing RIP.LNG file with the
RIP.LNG 2.3 language file.
2. Replace the existing RIPOM.CFG file with the
RIP.CFG configuration file so that RIP menu
commands are executed properly, and the initial
RIP poll is enabled.
3. Ensure that CEDIT (CONFIG.CTL) has the necessary
language settings for RIP operation.
The installation program will perform all steps shown
automatically.
WHAT TO DO AFTER RUNNING INSTALL
After you have run the installation program, you will need to
create RIP menus for your TBBS system. As mentioned above, you
can select from one of three ways to get this accomplished:
1) Make existing menus RIP compatible
2) Make new menus using supplied SDL samples
3) Make menu displays using RIPaint and {filename} method
Which one of these ways you pick depends on your specific needs
and preferences. These three options are discussed later.
ICONS FOR THE eSoft RIP KIT
Some of the internal displays within our RIP language file
require the user to have RIP icons resident on their computer,
not unlike most RIP implementations on bulletin board systems.
We have created and supplied you with the icons we use with the
RIP Kit. These files all have a .ICN file extension.
You may wish to provide these icons for download on your BBS so
that your users can obtain and install them in their RIP terminal
program. If your installed the RIP Sample Menus, a routine is
included to automatically download these icons file to a caller
if they do not have your "flag file". The flag file is a dummy
text file with a name of "E_<date>.ICN". The <date> portion
is defined within the PATHS.SDL file, which can be found in your
MENUS directory. This date should only change when you have
altered or added to the available icons included with the RIPkit.
See the PATHS.SDL file for more information.
IMPORTANT NOTE FOR USING TBBS MENUS WITH RIP
RIPkit 2.3 combined with TBBS 2.3 is RIP-aware without the use of
"stub" menus or the Type 204 menu command as required by previous
versions of RIPkit (1.0 and 1.1). It is important to note, howver,
that TBBS 2.3 internally implements fully backward compatible Type
204 commands which will allow your RIPkit 1.0 and 1.1 menus to
function properly as-is, but these commands are no longer required.
THE RIP.CFG FILE
The internal TBBS RIP.CFG file is fully backward compatible with
the RIPkit 1.0 and 1.1 RIPOM.CFG file. In addition it contains
new configuration commands to implement the extended RIP support
found in TBBS 2.3.
The new configuration command RIP_LANG: defines which language
letters are RIP format files. The syntax is as follows:
RIP_LANG: a[, b[,c...]]
Where a, b, c represent the letters of the language files defined
by LANGUAGES.BBS which are RIP format. Examples:
RIP_LANG: B
This defines that language B is RIP.
RIP_LANG: B, D
This defines that languages B and D are both RIP.
In TBBS 2.3, internal RIP support can be invoked automatically
for any user which has selected a language defined here as RIP.
The RIP_POLL: command has been added to force a poll of the
caller's ability to handle RIP and/or ANSI prior to the opening
language selection prompt. The syntax is:
RIP_POLL: NO|YES|AUTO=c
NO = don't do a RIP poll (default)
YES = do a RIP poll, record the answer, but take no other action.
AUTO=c do a RIP poll, record the answer, and if the answer is
that the caller can do RIP, immediately switch the
language to language "c".
Example:
RIP_POLL: AUTO=B
Means poll for RIP, and if the caller can do RIP, immediately
switch to language B.
Note: If AUTO is selected, and the language is switched by a
positive RIP poll, then any opening language selection menu prompt
is skipped. The opening language prompt will only occur if the
poll is negative AND CEDIT is set not to default language
selection to language "A".
The answer to a RIP poll may be queried through the use of the new
insertion parameter %CANRIP% which will return a "X" if the caller
is RIP capable, and a "." if he is not. This allows testing for
RIP ability in QAL or other TBBS operations later in the call.
If you have also set CEDIT to request an ANSI poll, then either
RIP_POLL: YES or RIP_POLL: AUTO=c will poll for both RIP and ANSI
at the opening menu. The normal position for an ANSI poll will be
suppressed in this case, as the poll will have already occurred as
the very first action after connect. From this poll the two
insertion parameters %CANANSI% and %CANRIP% will be set to reflect
the capabilities of the caller.
TBBS uses the language letter to determine whether RIP processing
is required or not. If a user selects a language listed in RIP_LANG:
then RIP processing is assumed. Any other language letter means
that RIP processing is not to be done.
The new command RIPSEQn_TYPES: has been added to allow the
definition of which TBBS internal commands require RIP prefix strings.
TBBS will automatically provide these prefixes when a RIP language
(as defined by the RIP_LANG: command) is selected, eliminating the
need for most TYPE=204 prefix string commands when building RIP
menus. The syntax of this command is:
RIPSEQn_TYPES: n[,n [,n...]]
Where n is the decimal menu command type(s) which should have the
RIPSEQn string as a prefix. You may also use a value of "OM" for
n to indicate that all option module calls should be prefixed with
the indicated RIP sequence, or "MENU" for n to indicate that all
menus should be prefaced with the indicated sequence.
Examples:
RIPSEQ1_TYPES: 1,2,4,20,34,46,48
RIPSEQ2_TYPES: 32,33, OM, MENU
These commands indicate that menu command types 1, 2, 4, 20, 34,
46 and 48 should be prefixed by RIPSEQ1: string whenever they are
selected if a RIP language is active. Menu command types 32, 33,
and all option modules (200 - 255) should be prefixed with RIPSEQ2
strings.
Note: With this definition, no further special menu handling is
required to assure proper handling of internal TBBS commands when
using RIP. All ANSI based commands will be properly displayed
to a RIP user, and fully integrated with whatever level of true RIP
support you add to your system.
The TYPE=204 command has been extended as follows:
TYPE=204 OPT DATA=0 <type> <opt data>
This command will execute the menu option specified ONLY if the
user is currently in a RIP language. If the user is not in a RIP
language, this command will be a no operation (NOP). This allows
menu commands to be conditionally executed based on whether the
caller has RIP active or not. Example:
TYPE=204 OPT DATA=0 5 RIP1
This command will do a TYPE=5, OPT DATA=RIP1 command only if the
caller is in a RIP language.
The RIP.CFG configuration file lists which TBBS menu commands
use which RIPscrip entrance sequences. It is not necessary to
adjust these settings, and changes to them are made at your
own risk.
The purpose of these sequences is to simply issue a RIP code AFTER
the user selects a function from the TBBS menu, but BEFORE the
function itself gets executed. This "send AFTER selection"
behavior is not one which TBBS supports by itself, hence the need
for entrance sequence definitions to perform this behavior.
RIP sequence #1 is defined as follows:
RIPSEQ1: ^A|*|w05002C0N11|1^[0000$STW$$MKILL$
This sequence is used for the following command types:
Type 1 File Display
Type 2 Multi-file display
Type 4 File areas
Type 14 File maintenance
Type 20 Keyword search
Type 22 Last 128 callers listing
Type 34 Raw download
Type 46 DIR download
Type 48 DIR delete
These command types are configured as sequence #1 as follows:
RIPSEQ1_TYPES: 1,2,4,14,20,22,34,46,48
RIP sequence #2 is defined as follows:
RIPSEQ2: ^A|*|w0000270N02|1K
This sequence is used for the following command types:
Type 32 Questionnaire entry
Type 33 Questionnaire display
ALL option modules
(Type 200 through Type 255)
These command types are configured as sequence #2 as follows:
RIPSEQ2_TYPES: 32,33,OM
RIP sequence #3 is defined as follows:
RIPSEQ3: ^A|1^[0000$SAVEALL$
(RIP sequence for type 7's so that exit from the FSE is handled
properly when message reading was not taking place)
This sequence is used for the following command types:
Type 7 Send message
This command type is configured as sequence #3 as follows:
RIPSEQ3_TYPES: 7
RIP sequence #4 is defined as follows:
RIPSEQ4: ^A|*|w0000270N02|1K
(RIP sequence to precede non-RIP menus while in RIP mode)
This sequence is used for the following command types:
Menus
(Displayed before every menu)
This command type is configured as sequence #4 as follows:
RIPSEQ4_TYPES: MENU
RIP MENUS
If you installed TBBS for the first time, and allowed the INSTALL
program to implement the RIP sample menus, your system will
already support RIPscrip emulation. The RIP sample menu system
is contained within the MENU_RIP.SDL file. Comments in that
SDL file will help you through any minor modifications you wish
to make.
If you had a TBBS 2.2 installation and have just upgraded to TBBS 2.3
and RIPkit 2.3, and did not allow the INSTALL program to implement
the RIP sample menus, then your system has been configured for RIP
emulation but will use your existing non-RIP menus. If you wish
your menus to use RIP as well, you will need to create the RIP
menus yourself, and modify the top level of your RIP menu
structure (if RIP is the only additional langauge installed on
your system, then that menu is 00LB) so that a RIP caller is sent
to your RIP main menu, rather than MENU0000.CTL.
If you had a TBBS -and- RIPkit 1.0/1.1 installation and have just
upgraded to TBBS 2.3 and RIPkit 2.3, then the new RIP.LNG has
replaced the old, but no menu changes have been made. Your RIP
installation should not be adversely affected. Because TBBS 2.3
no longer requires the use of Type 204 commands to execute, you
may convert your RIP caller menu entries to the standard format
if you wish. Example:
Old RIP Method: Type=204 Optdata=2 32 REGISTER
TBBS 2.3 Method: Type=32 Optdata=REGISTER
RIP MENUS -- MAKE MENU DISPLAYS USING RIPAINT AND {filename} METHOD
If you wish to design your own RIP menu design (rather than using
the RIP samples provided with RIPkit 2.3), you will need a copy of
RIPaint, not supplied with our RIP Kit. It is available from its
authors:
TeleGrafix Communications, Inc.
16458 Bolsa Chica #15
Huntington Beach, CA 92649
(714) 379-2131 Voice
(714) 379-2132 Fax
Essentially, you create menu displays using the RIPaint product,
and link them to your TBBS menus using the {filename} method shown
in Chapter 9 of your TBBS, in the section titled "Colorizing Your
Menus (ANSI Menu Displays)." Using the access flag you selected
during the installation process, you show the RIP file to your
callers conditional to that flag.
For this method to work well, you must have all of your menu text
contained in external files and referenced with the { } method.
If you have individual text menu entries, you must make sure that
the text doesn't display to your RIP callers. In other words,
only RIP files or text containing RIP codes should be displayed
to RIP callers; non-RIP text may corrupt RIP displays if allowed
to be passed to RIP callers. You will need to ensure that this
does not occur.
HINTS AND KINKS FOR USING RIP
Here are a number of comments and suggestions regarding the use
of RIP with TBBS:
1) Keep RIP displays to RIP callers, and non-RIP displays to
non-RIP callers. Sending RIP to a non-RIP user will simply mean
the user sees meaningless junk characters. Sending non-RIP
displays to RIP users can often result in corrupted RIP displays.
2) If you want to display a RIP scene to someone, you need to
make sure that you insert a clear screen (form feed character,
ASCII 12) every 10 to 20 lines in the RIP file to keep TBBS from
pausing with a "-More-" in the middle of the display (which will
corrupt the RIP display, and confuse users). To do this, you
must first create the RIP scene using RIPaint (or another RIP
paint or draw program), and save the scene to disk. Edit the
RIP file using a text editor. Every 10 to 20 lines, insert a
form feed character using your editor.
NOTE: TBBS 2.3 will not pause between pages when displaying a
file within a menu (using the curled-brackets "{filename}"
method). Therefore, clear screen codes do not need to be
inserted in these files.
3) RIP is not error corrected. On noisy lines, RIP displays
will become corrupted unless you and your users take advantage
of error correcting modems. There is not a way to work around
this limitation.
4) If you want to program RIP applications in TDBS, keep in mind
that a series of RIP codes ALWAYS must end with a carriage
return. If you use the ? or ?? output methods in TDBS, the
carriage return comes BEFORE the string that's sent, not AFTER.
Therefore, you must add a carriage return to the end of a
sequence, either by adding:
+chr(13)
to the end of the string, or by using this at the end:
? ""
Here is an example of this concept in RIP:
? chr(1)+"|1M0J2I083M1400000001"
? chr(1)+"|1M0K5008641400000002"
? chr(1)+"|1M0L7I088M1400000003"
? chr(1)+"|1M0MA008B41400000004"
? ""
You should also note that we recommend beginning RIP codes in
TDBS with a Ctrl-A character, chr(1), instead of the standard
bang symbol (!). This is a RIP synonym that allows a RIP code to
begin somewhere other than the beginning of a line, and has
proven to be much more reliable that the bang symbol.
We have also supplied a "RIP polling" demonstration in TDBS with
the RIP Kit (look in the RIPKIT sub-directory off your TBBS
directory) which you can use in your TDBS applications if desired
to automatically sense RIP compatibility.
5) Hot-keys in TBBS can interrupt RIP screens, with sometimes
undesirable results. If a user presses a hot-key in the middle
of a RIP menu display, TBBS will immediately process the hot-key
as usual. Interrupting a RIP display, however, can leave some
RIP settings (such as colors, fonts, etc.) such that they will
look "odd" or inappropriate on subsequently displayed functions.
You should warn users not to use hot-keys in the middle of menu
displays to avoid this behavior. If they use only buttons (part
of the RIP screen) with their mouse, this isn't a problem.
6) If you use fonts in your menu designs other than the default
font in the default size (1x), you must remember to reset the
font to the default within your menus. Otherwise, internal TBBS
functions may look "odd" or inappropriate in some cases. To
reset, as the last element of a menu design you're creating in
RIPaint, simply select the default font in 1x size from the font
menu. THIS MUST BE THE LAST THING YOU DO IN RIPAINT PRIOR TO
SAVING YOUR FINISHED MENU DESIGN. As an alternative, you can
edit the .RIP file with your text editor, making the very last
item in the .RIP file the following:
!|Y00000100|#|#|#
This must be the LAST thing in the file, and must begin flush
left (on a new line).
7) Please note that when a user executes a Type 31 to set message
preferences, they are presented with options to select from
ALWAYS, NEVER and ASK. However, regardless of which one they
select, their mode will always be set to ASK. This is
intentional.
8) When constructing a menu entry to activate a Type 31 command
in RIP, you should use the /S switch as Opt Data, so that the
current settings are displayed immediately. This makes for a proper
screen display to the user in RIP mode.